Active Directory Sync Troubleshooting

#1

Active Directory Sync Troublshooting

Table of Contents

General Troubleshooting:

  1. Confirm if the state of the safety switch: If the number of changes to be made is greater than 10% of your total number of learners, the sync will be rejected. This could be indicated that there may be too many groups or learners about to be synced which may or may not be desirable. Review your sync configuration to determine if the learners you are attempting to sync are correct.

  2. Confirm the correct secret key: Each account has a secret key assigned to it which will allow for the successful transmission of your learner information to the account. The key can be added while running the GUI-AD-Import.exe or be added to the config.json file in the AD sync folder. Be sure to also check for leading or trailing space characters in the field.

  3. Confirm your environment meets the requirements: The requirements to run our AD sync tool are dependent upon both system requirements as well as permissions. For the tool to run successfully, it is recommended to install on a machine with PowerShell 4.0 or greater and has permissions to access the active directory.

  4. Confirm proper permissions to run the app: There may be specific permissions requirements for access to read AD information or to write files onto the server that is being used to create our sync configuration.

  5. Confirm that the EU checkbox is checked ONLY when syncing to the EU instance: If your account is on the EU instance the box must be checked to sync to the EU or this task will fail.

Learners are not syncing:

  1. Users in the active directory that do not have a first name, last name, or email will not be selected by the tool. Review your user profile and confirm these fields are populated.

  2. The user is not in the groups selected. Review the security group you have selected in Active Directory to determine if the user should be part of that group. If not either add that user to the group or consider what other groups may need to be part of your scheduled syncs.

  3. The user may be in the exclusions list. Check the exclusion.csv file found in your Active Directory Sync folder to ensure they were not previously excluded. If they are in the exclusion list then it is suggested to re-run the GUI-AD-Import.exe to rebuild your exclusion list.

  4. The user is not in the domain selected. If you are using more than one domain then it is possible they are on another domain in your forest in which case they will not be part of the sync configuration for the domain you are working on.

The Tool gives a generic error and fails

Determine where the tool is being run. If not run on the domain controller try running the tool on the domain controller. This will help narrow the scope of the problem. If the tool fails while using Microsoft’s Remote Server Administration Tool (RSAT) but while on the Domain Controller it is likely a permissions error. If this occurs run the tool as an Administrator to see if this resolves the issue.

The tool takes too long to run or consumes too many resources:

Using the group selection field split the sync up. Make as many groups as needed within an active directory or use existing groups. For each group within the active directory create a folder for the AD-Sync Tool. The tool within that folder can then be configured to just pull a single group. Then in another separate folder have another copy of the tool that pulls a different group. When creating the automated tasks schedule the different folders to run at different times. Or, if not automating just run the tool several times each time selecting a different group. This may happen in scenarios when using an AWS server that doesn’t haven’t sufficient resources.

The Safety Switch is triggered unexpectedly:

Changes in the groups’ membership may trigger the safety switch. If the number of changes to be made is greater than 10% of your total number of learners, the sync will be rejected. Review the security groups listed in your sync by viewing the config.json file in your active directory folder and review those groups in the active directory to see if the group size has increased. It may be suggested to redo the configuration using the GUI-AD-Import.exe in the sync folder

Error: You cannot call a method on a null-valued expression

This is usually caused by the tool not being able to access the internet. Double-check that you are still connected to the internet and verify the server has access to connect in the firewall and security settings. If your exceptions need to be made for applications through your firewall port 443 will be utilized.

The scheduled task isn’t syncing successfully

Within the scheduled task verify that the path to the executable file is in the Start in (optional) field for the scheduled task:

ADsync_Troubleshooting
ADsync_Troubleshooting.png713×472 88.8 KB

Error: The term 'GetADFoest' is not recognized

When they receive this error, they usually don’t have the correct versions of PowerShell, or the PowerShell Active Directory Module is not installed. To confirm the version of PowerShell in user then use the cmdlet "get-host" to confirm which version of PowerShell is installed.

ADsync_Troubleshooting2
ADsync_Troubleshooting2.png1134×256 7.68 KB

If this error appears it is likely that Active Directory needs to be installed on that machine. In Server Manager, click Add Features, and then: Select Active Directory module for Windows PowerShell in Remote Server Administration Tools > Role Administration Tools > AD DS and AD LDS Tools. Alternatively, this can be installed in PowerShell using the following:

Import-Module ServerManager
Add-WindowsFeature RSAT-AD-PowerShell

For more information on this installation method click here to view Microsoft’s article on the subject.

Error: Access to the path is denied

They may not have the proper permissions. Right-click on the GUI-AD-Import tool and select “run as admin”.

ADsync_Troubleshooting3
ADsync_Troubleshooting3.png785×295 8.86 KB

Error: Cannot bind argument to parameter 'InputObject' because it is null

A user is missing an email address.

ADsync_Troubleshooting4
ADsync_Troubleshooting4.png797×338 12.9 KB

PowerShell commands used

Our tool utilizes a series of powershell cmdlets to query Active Directory and create configurations files that are used to transmit information to InfosecIQ. If you would like more information about these different cmdlets you can also review Microsoft’s documentation on this topic:

The following commands used by the tool are specific to the AD Module for powershell:

Get-ADForest - Queries which domains are in the forest

Get-ADUser - Queries user object in active directory and is used to return properties about the user such as name, email, department, etc.

Get-ADUser -Filter -Properties

Get-ADUser -Filter -Properties | Export-CSV C:\Users\Administrator\Desktop\ActiveDirectorySynchronizer5.3\ActiveDirectorySynchronizer\userdetails.csv

Get-ADGroup - Queries the security group object within active directory and returns information and what the group is and what users are in the group

Get-ADGroup -filter {groupCategory -eq 'Security'} | Select Name | Sort-Object Name


Get-ADGroup -Filter { groupCategory -eq 'security' } | Select name | Export-CSV C:\Users\Administrator\Desktop\ActiveDirectorySynchronizer5.3\ActiveDirectorySynchronizer\listsecgroups.csv

The following commands are basic commands available in Powershell

Export-Csv - The Export-CSV cmdlet creates a CSV file of the objects that you submit. Each object is a row that includes a comma-separated list of the object’s property values. You can use the Export-CSV cmdlet to create spreadsheets and share data with programs that accept CSV files as input.

Import-Csv - The Import-Csv cmdlet creates table-like custom objects from the items in CSV files. Each column in the CSV file becomes a property of the custom object and the items in rows become the property values. Import-Csv works on any CSV file, including files that are generated by the Export-Csv cmdlet.

Write-Host - The Write-Host cmdlet customizes output. You can specify the color of text by using the ForegroundColor parameter, and you can specify the background color by using the BackgroundColor parameter. The Separator parameter lets you specify a string to use to separate displayed objects. The particular result depends on the program that is hosting PowerShell.

Test-Path - Determines whether all elements of the path exist. It returns $True if all elements exist and $False if any are missing. It can also tell whether the path syntax is valid and whether the path leads to a container or a terminal or leaf element.

Out-GridView - The Out-GridView cmdlet sends the output from a command to a grid view window where the output is displayed in an interactive table. Because this cmdlet requires a user interface, it does not work on Server Core installations of Windows Server. You can use the following features of the table to examine your data:

Hide, Show, and Reorder Columns: To hide, show, or reorder a column, right-click a column header and then click “Select Columns.”

Sort. To sort the data, click a column header. Click again to toggle from ascending to descending order.

Quick Filter. Use the “Filter” box at the top of the window to search the text in the table. You can search for text in a particular column, search for literals, and search for multiple words.

Criteria Filter. Use the “Add criteria” drop-down menu to create rules to filter the data. This is very useful for very large data sets, such as event logs.

Copy and paste. To copy rows of data from Out-GridView, press CTRL+C (copy). You can paste the data into any text or spreadsheet program.

Out-String - The Out-String cmdlet converts the objects that Windows PowerShell manages into an array of strings. By default, Out-Stringaccumulates the strings and returns them as a single string, but you can use the Stream parameter to direct Out-String to return one string at a time. This cmdlet lets you search and manipulate string output as you would in traditional shells when object manipulation is less convenient.

Select-Object - The Select-Object cmdlet selects specified properties of an object or set of objects. It can also select unique objects, a specified number of objects, or objects in a specified position in an array. To select objects from a collection, use the First, Last, Unique, Skip, and Index parameters. To select object properties, use the Property parameter. When you select properties, Select-Object returns new objects that have only the specified properties.

Get-Content - The Get-Content cmdlet gets the content of the item at the location specified by the path, such as the text in a file or the content of a function. For files, the content is read one line at a time and returns a collection of objects, each of which represents a line of content.

ConvertFrom-Json - The ConvertFrom-Json cmdlet converts a JavaScript Object Notation (JSON) formatted string to a custom PSCustomObject object that has a property for each field in the JSON string. JSON is commonly used by web sites to provide a textual representation of objects. The JSON standard does not prohibit usage that is prohibited with a PSCustomObject. For example, if the JSON string contains duplicate keys, only the last key is used by this cmdlet.

ConvertTo-Csv - The ConvertTo-CSV cmdlet returns a series of comma-separated value (CSV) strings that represent the objects that you submit. You can then use the ConvertFrom-Csv cmdlet to recreate objects from the CSV strings. The objects converted from CSV are string values of the original objects that contain property values and no methods.

Invoke-WebRequest - The Invoke-WebRequest cmdlet sends HTTP, HTTPS, FTP, and FILE requests to a web page or web service. It parses the response and returns collections of forms, links, images, and other significant HTML elements.